@theronap/cortex-mcp 0.9.11 → 0.9.13

package/bin/cortex-mcp.mjs

@@ -90,6 +90,12 @@ if (cmd === 'setup') {
   await runCapture()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'resolve') {
+  // Entity identity dedup: judge the server-flagged fuzzy duplicate pairs locally via `claude -p`.
+  const { runResolve } = await import('../lib/resolve.mjs')
+  await runResolve()
+  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

@@ -4,6 +4,20 @@ import { resolve } from 'path'
 import { createHash } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 import { extractSession } from './edge_extract.mjs'
+import { extractTyped } from './extract_typed.mjs'
+
+// Fetch the node-type registry (global + this org's custom types) — the catalog the typed extractor
+// produces against. Best-effort: null on any failure (typed extraction is then skipped, never blocks capture).
+async function fetchRegistry(base, token) {
+  try {
+    const res = await fetchCortex(`${base}/api/node-types`, { headers: { Authorization: `Bearer ${token}` } })
+    if (!res.ok) return null
+    const j = await res.json().catch(() => ({}))
+    return Array.isArray(j.types) ? j.types : null
+  } catch {
+    return null
+  }
+}
 
 // Project name from the hook cwd — cross-platform. Windows hooks send backslash paths,
 // and splitting on '/' alone turned the WHOLE path into one garbage project slug
@@ -112,6 +126,19 @@ export async function runCapture() {
     ? { ...common, summary: extracted.summary, people: extracted.people, entities: extracted.namedEntities }
     : { ...common, transcript }
 
+  // Parallel typed extraction (OPT-IN via CORTEX_TYPED): registry-driven typed notes, sent ALONGSIDE the
+  // people/entities above. The server's typedNotes receiver persists them additively. Off by default so it
+  // never adds a 2nd `claude` call / latency until verified; flip to default once typed ≥ the blob path.
+  if (process.env.CORTEX_TYPED && transcript) {
+    try {
+      const registry = await fetchRegistry(base, token)
+      if (registry?.length) {
+        const typed = extractTyped(transcript, registry)
+        if (typed?.notes?.length) ingestBody.typedNotes = typed.notes
+      }
+    } catch { /* best-effort — never block capture */ }
+  }
+
   let res
   try {
     res = await fetchCortex(`${base}/api/ingest`, {

package/lib/extract_typed.mjs

@@ -0,0 +1,68 @@
+import { spawnSync } from 'child_process'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// Typed extraction (synthesis slice 2) — registry-driven. Given a transcript + the node_types registry,
+// the LLM emits TYPED NOTES (one per real thing that happened / was mentioned) conforming to the type
+// definitions, instead of the old loose {summary, people, namedEntities} blob. Runs locally on the
+// subscription (edgeSafeEnv strips ANTHROPIC_*). PARALLEL to edge_extract.mjs — does NOT replace it yet;
+// built to be tested in isolation, then wired into capture once proven (slice 2b).
+//
+// Per the ontology (cortex-node-ontology-spec): programmatic fields are filled by the caller from source
+// metadata BEFORE this runs; here the LLM fills only what the text supports, self-flags llm_filled fields,
+// and uses "unknown" for required fields it can't determine (→ red-link downstream). It may also COIN a
+// new type (open registry) when nothing fits.
+
+function typeCard(t) {
+  const fields = (arr) => (Array.isArray(arr) ? arr : []).map((f) => `${f.field}${f.note ? ` (${f.note})` : ''}`).join(', ')
+  return `• ${t.name} [${t.layer}]${t.applies_to?.length ? ` applies_to:${t.applies_to.join('/')}` : ''}\n` +
+    `    required: ${fields(t.required_fields) || '—'}\n` +
+    `    optional: ${fields(t.optional_fields) || '—'}\n` +
+    `    how: ${t.extraction_instructions}`
+}
+
+export function extractTyped(transcript, registry, opts = {}) {
+  const text = (transcript ?? '').trim()
+  if (!text || !Array.isArray(registry) || !registry.length) return null
+  const catalog = registry.map(typeCard).join('\n')
+  const prompt =
+    'You are building an organization knowledge graph from a work session. Using ONLY the node/note types ' +
+    'in the CATALOG below, emit the typed notes this session supports — one per real thing that happened ' +
+    '(actions, decisions, communications) or entity referenced (people, projects, etc.).\n\n' +
+    'RULES:\n' +
+    '- Fill a field ONLY if the text supports it. If a REQUIRED field is unknowable, set it to "unknown".\n' +
+    '- List the fields YOU inferred (vs. ones obviously given) in "llm_filled".\n' +
+    '- Reference other things by name (e.g. actors:["Jane Doe"]) — do not invent ids.\n' +
+    '- NEVER invent numbers (amounts, values, metrics) — "unknown" if not explicitly stated.\n' +
+    '- Be conservative: only emit a note for something genuinely present. Empty array is fine.\n' +
+    '- If something important fits NO type, you may coin one: add it to "new_types" with ' +
+    '{name, layer, required_fields:[{field}], why}.\n\n' +
+    'Return ONLY minified JSON: {"notes":[{"type","fields":{...},"llm_filled":[...]}],"new_types":[...]}.\n\n' +
+    '--- CATALOG ---\n' + catalog + '\n\n--- SESSION ---\n' + text.slice(0, 12000) + '\n--- END ---'
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', opts.model ?? process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', 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 parseTyped(r.stdout)
+  } catch {
+    return null
+  }
+}
+
+export function parseTyped(out) {
+  if (!out) return null
+  const start = out.indexOf('{')
+  const end = out.lastIndexOf('}')
+  if (start < 0 || end <= start) return null
+  try {
+    const o = JSON.parse(out.slice(start, end + 1))
+    return {
+      notes: Array.isArray(o.notes) ? o.notes : [],
+      new_types: Array.isArray(o.new_types) ? o.new_types : [],
+    }
+  } catch {
+    return null
+  }
+}

package/lib/resolve.mjs

@@ -0,0 +1,103 @@
+import { spawnSync } from 'child_process'
+import { fetchCortex, resolveBase, classify } from './diagnose.mjs'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// `cortex-mcp resolve` — the JUDGE half of entity identity dedup (Grey harvest). The server FLAGS the
+// fuzzy band of near-duplicate non-person entities (GET /api/resolve-candidates); this command judges
+// each pair LOCALLY via `claude -p` (the engine preference — the server never calls the metered API)
+// and pushes decisions back (POST /api/resolve-apply): confident-same → entity_merges, else → rejected
+// so the pair never re-flags. Conservative by construction. Always exits cleanly.
+
+export async function runResolve() {
+  // recursion guard (we spawn `claude --print`; if its Stop hook fires capture, that 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 the flagged candidate pairs
+  let candidates = []
+  try {
+    const res = await fetchCortex(`${base}/api/resolve-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: resolve-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: resolve fetch failed — ${e.message}\n`); return }
+
+  if (!candidates.length) { process.stderr.write('cortex: no duplicate candidates to judge\n'); return }
+  process.stderr.write(`cortex: judging ${candidates.length} candidate pair(s) locally…\n`)
+
+  // 2. judge locally on the subscription
+  const decisions = judgeCandidates(candidates)
+  if (decisions === null) { process.stderr.write('cortex: judge unavailable (is `claude` on PATH?) — skipping\n'); return }
+
+  // 3. apply judged decisions
+  try {
+    const res = await fetchCortex(`${base}/api/resolve-apply`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ decisions }),
+    })
+    if (res.ok) {
+      const j = await res.json().catch(() => ({}))
+      process.stderr.write(`cortex: dedup — merged ${j.merged ?? 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: resolve-apply failed — ${d.message}\n`)
+    }
+  } catch (e) { process.stderr.write(`cortex: resolve-apply failed — ${e.message}\n`) }
+}
+
+// ONE `claude --print` call judges every pair. Returns DedupDecision[] for the apply endpoint, or null
+// if the CLI is unavailable. Every judged pair (merge AND non-merge) is returned so non-merges get
+// recorded as rejected and never re-flag.
+function judgeCandidates(candidates) {
+  const list = candidates.map((c, i) =>
+    `[${i}] kind=${c.kind}\n` +
+    `  A: "${c.aName}" (e.g. record: ${c.aSample ?? 'n/a'}; ${c.aMentions} mentions)\n` +
+    `  B: "${c.bName}" (e.g. record: ${c.bSample ?? 'n/a'}; ${c.bMentions} mentions)\n` +
+    `  shared records: ${c.sharedRecords}; name similarity: ${Number(c.sim).toFixed(2)}`,
+  ).join('\n')
+  const prompt =
+    'You are deduplicating an organization knowledge graph. For each candidate pair below, decide ' +
+    'whether A and B are the SAME real-world entity (a spelling/abbreviation/variant of ONE thing) or ' +
+    'DIFFERENT things that merely have similar names. Be CONSERVATIVE: only merge when confident; when ' +
+    'in doubt, do NOT merge. Same kind only.\n' +
+    'Return ONLY a minified JSON array — one object per pair: ' +
+    '{"i":<index>,"merge":<true|false>,"confidence":<0..1>,"reason":"<short>"}.\n\n' + list
+  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 parseDecisions(r.stdout, candidates)
+  } catch {
+    return null
+  }
+}
+
+function parseDecisions(out, candidates) {
+  const start = out.indexOf('[')
+  const end = out.lastIndexOf(']')
+  if (start < 0 || end <= start) return []
+  let arr
+  try { arr = JSON.parse(out.slice(start, end + 1)) } catch { return [] }
+  if (!Array.isArray(arr)) return []
+  const decisions = []
+  for (const d of arr) {
+    const c = candidates[Number(d?.i)]
+    if (!c) continue
+    decisions.push({
+      aId: c.aId, bId: c.bId, kind: c.kind,
+      merge: !!d.merge,
+      confidence: Number(d.confidence) || 0,
+      reason: typeof d.reason === 'string' ? d.reason.slice(0, 200) : undefined,
+    })
+  }
+  return decisions
+}

package/package.json

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