@theronap/cortex-mcp 0.9.5 → 0.9.7

package/bin/cortex-mcp.mjs

@@ -17,7 +17,13 @@
  * Get your token from the Cortex console → Connect your AI.
  */
 
-const VERSION = '0.9.5'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+// VERSION = package.json, the single source of truth. NEVER hardcode it: a stale constant here is
+// exactly what shipped 0.9.6 as "0.9.5", so `setup` pinned the wrong version into every config and
+// no amount of cache-clearing/@version could fix an install. Derive it so it can never drift again.
+const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 

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

@@ -70,9 +70,12 @@ export async function runSetup(argv, version) {
     )
     process.exit(1)
   }
-  // Pin the wired commands to the installed version so the config can't later run a stale
-  // cached build (npx may reuse a cached older version for an unpinned spec).
-  const spec = version ? `${PKG}@${version}` : PKG
+  // Wire the moving `stable` dist-tag — NOT a frozen version. A bare spec lets npx reuse a stale
+  // cached build; a frozen `@x.y.z` freezes the machine on that version forever (the 0.9.5→0.9.6
+  // freeze that stranded a pilot install). A tag is re-resolved by npx against the registry, so
+  // machines pick up promoted releases on next launch without re-running setup. Promote a
+  // validated build with:  npm dist-tag add @theronap/cortex-mcp@<version> stable
+  const spec = `${PKG}@stable`
   const base = resolveBase(process.env.CORTEX_URL)
   const home = homedir()
   const claudeJson = join(home, '.claude.json')

package/package.json

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