@theronap/cortex-mcp 0.9.4 → 0.9.6

package/bin/cortex-mcp.mjs

@@ -17,7 +17,7 @@
  * Get your token from the Cortex console → Connect your AI.
  */
 
-const VERSION = '0.9.4'
+const VERSION = '0.9.5'
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
@@ -35,6 +35,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `sessions flow into the org automatically. Restart Claude Code after.\n\n` +
     `Subcommands:\n` +
     `  setup <token>   wire MCP server + capture hook into ~/.claude config\n` +
+    `  repair          re-run setup at the latest version using your existing token (no token needed)\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` +
     `  skills          install/repair the managed Cortex skills (also wired by setup)\n` +
@@ -58,6 +59,13 @@ if (cmd === 'setup') {
   await runSetup(rest, VERSION)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'repair' || cmd === 'update') {
+  // Re-run setup at THIS version using the already-wired token (no token arg needed). Fixes a
+  // machine set up with an older version: re-pins MCP + hooks, reinstalls skills to the flat path.
+  const { runRepair } = await import('../lib/setup.mjs')
+  await runRepair(VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'doctor') {
   const { runDoctor } = await import('../lib/doctor.mjs')
   process.exitCode = await runDoctor()

package/lib/capture.mjs

@@ -1,6 +1,7 @@
 import { readFileSync } from 'fs'
 import { homedir } from 'os'
 import { resolve } from 'path'
+import { createHash } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 
 // Project name from the hook cwd — cross-platform. Windows hooks send backslash paths,
@@ -75,6 +76,16 @@ export async function runCapture() {
 
   if (!transcript && !hook.session_id) { process.stderr.write('cortex: empty session, skipping\n'); return }
 
+  // T11: digest node refs surfaced to this session (stashed by the MCP server's my_context, keyed by
+  // cwd). Forwarded as hydratedFrom so the materializer excludes this session from the digests it
+  // consumed (feedback-loop guard). Best-effort + inert when absent (digest flag off / no my_context).
+  let hydratedFrom = []
+  try {
+    const key = createHash('sha1').update(hook.cwd || process.cwd()).digest('hex').slice(0, 16)
+    const parsed = JSON.parse(readFileSync(resolve(homedir(), '.cortex', 'brain-refs', `${key}.json`), 'utf8'))
+    if (Array.isArray(parsed.refs) && Date.now() - (parsed.ts ?? 0) < 12 * 3600 * 1000) hydratedFrom = parsed.refs
+  } catch { /* none — guard stays a no-op */ }
+
   let res
   try {
     res = await fetchCortex(`${base}/api/ingest`, {
@@ -87,6 +98,8 @@ export async function runCapture() {
         transcript,
         title: `Worked in ${repo}`,
         payload: { session_id: hook.session_id, cwd: hook.cwd },
+        captureSource: 'hook', // T8: fallback writer — never clobbers a cortex-log ('skill') record
+        ...(hydratedFrom.length ? { hydratedFrom } : {}),
       }),
     })
   } catch (e) {

package/lib/server.mjs

@@ -4,6 +4,7 @@ import { z } from 'zod'
 import { writeFileSync, mkdirSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
+import { createHash } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
@@ -30,8 +31,19 @@ export async function runServer(version) {
       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 { context } = await res.json()
+    const { context, brainRefs } = await res.json()
     cache = { text: context, ts: now }
+    // T11: stash the digest node refs surfaced this fetch so capture.mjs can forward them as
+    // hydrated_from at the session's ingest (feedback-loop guard). Keyed by cwd so the matching
+    // session picks them up. Best-effort + inert when brainRefs is empty (digest flag off).
+    try {
+      if (Array.isArray(brainRefs) && brainRefs.length) {
+        const dir = join(homedir(), '.cortex', 'brain-refs')
+        mkdirSync(dir, { recursive: true })
+        const key = createHash('sha1').update(process.cwd()).digest('hex').slice(0, 16)
+        writeFileSync(join(dir, `${key}.json`), JSON.stringify({ refs: brainRefs, ts: now }))
+      }
+    } catch { /* best-effort — never break context serving */ }
     return context
   }
 
@@ -60,6 +72,45 @@ export async function runServer(version) {
     },
   )
 
+  // 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
+  // one record; without it the curated log still lands as its own authoritative record.
+  server.registerTool(
+    'log_session',
+    {
+      title: 'Log this session to Cortex',
+      description: 'Persist a CURATED summary of this work session as its durable Cortex record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. Pass sessionId (the Claude Code session id) if you have it so this dedupes with the auto-capture of the same session.',
+      inputSchema: {
+        summary: z.string().describe('the curated session summary (what was done, decided, left open) — becomes the durable record'),
+        project: z.string().optional().describe('project key/name this session worked in'),
+        title: z.string().optional().describe('short title for the session'),
+        sessionId: z.string().optional().describe('the Claude Code session id (dedupes with the auto-capture hook of the same session)'),
+      },
+    },
+    async ({ summary, project, title, sessionId }) => {
+      const res = await fetchCortex(`${BASE}/api/ingest`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          source: 'claude-code',
+          captureSource: 'skill',
+          summary,
+          ...(project ? { project } : {}),
+          ...(title ? { title } : {}),
+          ...(sessionId ? { sessionId } : {}),
+          payload: { via: 'log_session' },
+        }),
+      })
+      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 j = await res.json().catch(() => ({}))
+      return { content: [{ type: 'text', text: `Logged to Cortex (authoritative): "${j.title ?? title ?? 'session'}" — ${j.inserted ? 'new record' : 'updated existing'}.` }] }
+    },
+  )
+
   server.registerTool(
     'session_context',
     {

package/lib/setup.mjs

@@ -215,3 +215,35 @@ export async function runSetup(argv, version) {
   log(`   Console: ${base}`)
   log('')
 }
+
+// Find the token already wired on this machine, so `repair` can re-run setup without re-pasting it.
+// Checks Claude's config first, then Codex's config.toml.
+export function readWiredToken() {
+  try {
+    const cfg = readJson(join(homedir(), '.claude.json'))
+    const t = cfg?.mcpServers?.cortex?.env?.CORTEX_TOKEN
+    if (t) return t
+  } catch { /* fall through */ }
+  try {
+    const toml = readFileSync(join(homedir(), '.codex', 'config.toml'), 'utf8')
+    const m = toml.match(/\[mcp_servers\.cortex\.env\][\s\S]*?CORTEX_TOKEN\s*=\s*"([^"]+)"/)
+    if (m) return m[1]
+  } catch { /* fall through */ }
+  return null
+}
+
+// `repair`: re-run the FULL setup at THIS version using the already-wired token. The one-command fix
+// for a machine set up with an older version (e.g. when skills were installed to the old nested path,
+// or the hooks are pinned to a stale version). No token argument needed.
+export async function runRepair(version) {
+  const token = readWiredToken()
+  if (!token) {
+    process.stderr.write(
+      'No existing Cortex token found in ~/.claude.json or ~/.codex/config.toml.\n' +
+      'Run setup once with your token:  npx -y @theronap/cortex-mcp setup <YOUR_TOKEN>\n',
+    )
+    process.exit(1)
+  }
+  process.stdout.write('Cortex repair — re-running setup with your existing token at this version…\n')
+  await runSetup([token], version)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "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

@@ -6,11 +6,20 @@ description: Close out a work session into Cortex — summarize what happened, c
 > **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
 > restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
 
+## Model: session-primary, daily-derived
+
+The **session is the primary atomic unit** — one session = one durable Cortex record (via
+`log_session`, keyed by `sessionId`), which is also the per-record privacy unit (`set_record_privacy`
+is per record). Any "what happened today / this week" view is a **derived rollup** over those session
+records, never a separately-authored primary. This mirrors records(atomic) → digests(derived); the
+personal `/log` skill follows the same shape against the local brain.
+
 ## When to use
 
-At the end of a Claude Code session, or after finishing a meaningful phase of work. Cortex already
-captures your sessions automatically in the background — this skill is the *deliberate* close-out: it
-produces a clean, structured summary and confirms the org received it.
+At the end of a Claude Code session, or after finishing a meaningful phase of work. Cortex keeps a
+background auto-capture as a fallback, but this skill is the *authoritative* close-out: it composes a
+clean, structured summary and persists THAT as the session's durable record (superseding the
+auto-capture's raw-transcript re-derivation).
 
 ## Inputs
 
@@ -22,15 +31,18 @@ No arguments. Read the conversation context.
    the projects, files, and people involved.
 2. **Surface org-relevant signal** — blockers, decisions, handoffs, and anyone you coordinated with.
    These are the things a teammate or manager would want to know without reading the whole transcript.
-3. **Confirm capture** — check the Cortex MCP is connected (`my_context` returns your context). Your
-   session flows to the org automatically at session end via the capture hook; if `my_context` errors,
-   tell the user their session may not be captured and to run `npx -y @theronap/cortex-mcp doctor`.
-4. **Flag privacy** — 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.
+3. **Persist it as the durable record** — call the `log_session` MCP tool with your curated `summary`
+   (plus `project`, and the Claude Code `sessionId` if you know it). This writes YOUR summary as the
+   session's authoritative Cortex record (`capture_source='skill'`). The background auto-capture is a
+   fallback and will not overwrite it; passing the same `sessionId` the auto-capture uses dedupes them
+   onto one record. This — not the raw-transcript re-derivation — is the canonical record going forward.
+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.
 
 ## Output
 
-A short structured summary:
+After calling `log_session`, show a short structured summary:
 
 ```markdown
 ## Session summary
@@ -39,12 +51,12 @@ A short structured summary:
 **Decisions:** decision 1; decision 2
 **Open / blocked:** anything unresolved or waiting on someone
 **Coordinated with:** people involved
-**Capture:** ✅ flowing to Cortex  (or ⚠ not connected — run doctor)
+**Logged:** ✅ persisted as the session's record (authoritative)  (or ⚠ log_session errored — run doctor)
 ```
 
 ## Safety rules
 
-- This skill only summarizes and reports. It never sends external messages, never deletes anything,
-  and never changes access on a record without the user explicitly asking.
-- Raw session text stays on this machine — only the summary-grade record reaches the org, scoped by
-  access rules.
+- This skill summarizes and persists the session's record (via `log_session`). It never sends external
+  messages, never deletes anything, and never changes access on a record without the user explicitly asking.
+- Raw session text stays on this machine — only the curated summary-grade record reaches the org, scoped
+  by access rules.