@theronap/cortex-mcp 0.9.17 → 0.9.19

package/bin/cortex-mcp.mjs

@@ -103,6 +103,13 @@ 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.
@@ -130,6 +137,12 @@ if (cmd === 'setup') {
   // Install / repair the managed Cortex skills repository. No network — exits naturally.
   const { runSkills } = await import('../lib/skills.mjs')
   process.exitCode = await runSkills(rest)
+} 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()
 } else {
   // Default: run the MCP server (stays alive; never exits).
   const { runServer } = await import('../lib/server.mjs')

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/precompact.mjs

@@ -0,0 +1,16 @@
+// 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(
+    'Cortex: 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',
+  )
+}

package/lib/server.mjs

@@ -580,5 +580,89 @@ export async function runServer(version) {
     },
   )
 
+  // ── ③ LIVE WIKI AUTHORING ([[cortex-wiki-authoring-spec]]) ────────────────────────────────────────
+  // Two tools the working session uses to AUTHOR its understanding into the org wiki while it's hot:
+  //   authoring_context → the companion call (§3): fetch the visible NAMESPACE + the node-type connection
+  //     rules BEFORE writing, so the page links canonically (the L2 lever).
+  //   author           → the write (§9 step 3/4): hand Cortex a finished page (summary + sections WITH
+  //     inline [[links]]); the server runs the resolution pass + tier-safe 2B write.
+
+  server.registerTool(
+    'authoring_context',
+    {
+      title: 'Authoring context (call before author)',
+      description:
+        'Fetch the scaffolding to author a Cortex wiki node: the canonical NAMESPACE (existing node names — link to these with the EXACT name inside [[ ]]) and the node-type CONNECTION RULES (what kinds of links to look for). ALWAYS call this BEFORE `author` so the page links to real nodes by their established names instead of minting synonyms. Reference a node in the namespace as [[Name]]; if you reference something real that is NOT in the namespace, still write [[Name]] — that is a red-link marking a node worth creating.',
+      inputSchema: {
+        kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('the node type you are about to author (default project)'),
+      },
+    },
+    async ({ kind }) => {
+      const k = kind ?? 'project'
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/authoring-context?kind=${k}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not fetch authoring context: ${e.message}` }] }
+      }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not fetch authoring context: ${d.message}` }] }
+      }
+      const { connectionRules, namespace } = await res.json()
+      const ns = Array.isArray(namespace) ? namespace : []
+      const nsList = ns.map((n) => `[[${n}]]`).join(', ')
+      const text =
+        `Authoring a "${k}" node. Connection rules (kinds of links to look for):\n${connectionRules}\n\n` +
+        `NAMESPACE — ${ns.length} existing nodes; link with the EXACT name inside [[ ]]:\n${nsList}\n\n` +
+        `Now author the page (summary + sections) with inline [[links]] woven into the prose. Link, do not restate. ` +
+        `For something real that is not in this namespace, still write [[Name]] (a red-link). Then call \`author\`.`
+      return { content: [{ type: 'text', text }] }
+    },
+  )
+
+  server.registerTool(
+    'author',
+    {
+      title: 'Author a wiki node (live, while it is hot)',
+      description:
+        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log).',
+      inputSchema: {
+        kind: z.enum(['project', 'person', 'org', 'user']).describe('the node type'),
+        name: z.string().describe('the EXACT canonical node name (from the namespace), e.g. "Cortex" or "Theron Peterson"'),
+        summary: z.string().describe('one-sentence summary of what this is and its current state (may contain [[links]])'),
+        sections: z.array(z.object({
+          heading: z.string().describe('e.g. Overview, Current state, Decisions, Open threads, People'),
+          body: z.string().describe('dense markdown WITH inline [[links]] where the prose references another node'),
+        })).describe('3-5 sections; the page body'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('visibility tier (default accessible — the shareable page)'),
+      },
+    },
+    async ({ kind, name, summary, sections, tier }) => {
+      const pages = [{ tier: tier ?? 'accessible', summary, sections: Array.isArray(sections) ? sections : [] }]
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/author`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ kind, name, pages }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not author "${name}": ${e.message}` }] }
+      }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not author "${name}": ${d.message}` }] }
+      }
+      const out = await res.json()
+      const blue = out?.links?.blue ?? 0
+      const red = out?.links?.red ?? 0
+      const redList = Array.isArray(out?.redLinks) && out.redLinks.length ? `\nRed-links (wanted nodes): ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
+      const note = out?.built ? `Authored "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${red} red.${redList}`
+        : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.`
+      return { content: [{ type: 'text', text: note }] }
+    },
+  )
+
   await server.connect(new StdioServerTransport())
 }

package/lib/setup.mjs

@@ -181,6 +181,22 @@ export async function runSetup(argv, version) {
     }
     sgrp.hooks.push({ type: 'command', command: snapshotCmd })
 
+    // PreCompact "author now" reminder (③ live wiki authoring, best-effort). Merges into the PreCompact
+    // array WITHOUT clobbering other hooks (filters only prior cortex entries, then appends to the ''
+    // matcher group). A hook can't force a turn — this just nudges the session to sweep understanding
+    // into the wiki before compaction; the /log skill is the hard backstop.
+    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 ?? ''))
+      }
+    }
+    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 })
+
     ensureDir(settingsJson)
     writeFileSync(settingsJson, JSON.stringify(s, null, 2))
     log(`  ✓ Capture hook + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)

package/package.json

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

package/skills/log/SKILL.md

@@ -39,6 +39,15 @@ No arguments. Read the conversation context.
 4. **Confirm + flag privacy** — `log_session` returns a confirmation; if it errors, tell the user to
    run `npx -y @theronap/cortex-mcp doctor`. If any record from this session should be confidential,
    note it so the user can mark it (`set_record_privacy`). Default is org-visible under access rules.
+5. **Sweep the wiki (author what you now understand)** — the HARD backstop for live authoring
+   ([[cortex-wiki-authoring-spec]] D2). For each node whose understanding meaningfully advanced this
+   session (the project(s) worked on, people you coordinated with, and yourself when your own focus
+   shifted): call `authoring_context` for its kind, then `author` to write the page from your compiled
+   understanding — what it IS, where it stands, dated decisions, open threads, key people — with inline
+   `[[links]]` to other nodes (canonical names from the namespace; red-links for wanted-but-absent
+   nodes). This is a synthesis, not a transcript dump. Skip nodes you didn't actually advance. If you
+   already authored a node mid-session and nothing changed since, `author` will report "no change" —
+   that's fine.
 
 ## Output
 
@@ -52,6 +61,7 @@ After calling `log_session`, show a short structured summary:
 **Open / blocked:** anything unresolved or waiting on someone
 **Coordinated with:** people involved
 **Logged:** ✅ persisted as the session's record (authoritative)  (or ⚠ log_session errored — run doctor)
+**Wiki authored:** [[Node A]], [[Node B]] — pages updated (or "— nothing advanced this session")
 ```
 
 ## Safety rules