@theronap/cortex-mcp 0.9.78 → 0.9.79
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -3
- package/bin/cortex-mcp.mjs +22 -38
- package/lib/capture.mjs +1 -1
- package/lib/code_graph_cli.mjs +1 -1
- package/lib/context_log.mjs +5 -5
- package/lib/diagnose.mjs +11 -81
- package/lib/docs_scan.mjs +4 -4
- package/lib/doctor.mjs +11 -48
- package/lib/editors/antigravity.mjs +1 -1
- package/lib/editors/claude.mjs +14 -29
- package/lib/editors/codex.mjs +1 -1
- package/lib/editors/cursor.mjs +1 -1
- package/lib/editors/index.mjs +1 -1
- package/lib/graphify_sync.mjs +4 -49
- package/lib/grep_cli.mjs +1 -1
- package/lib/hydrate.mjs +1 -1
- package/lib/imessage_send.mjs +1 -1
- package/lib/ingest_folder.mjs +2 -2
- package/lib/install.mjs +6 -6
- package/lib/precompact.mjs +16 -0
- package/lib/redact.mjs +1 -1
- package/lib/resolve.mjs +12 -62
- package/lib/server.mjs +51 -139
- package/lib/setup.mjs +10 -11
- package/lib/skills.mjs +17 -89
- package/lib/uninstall.mjs +3 -3
- package/package.json +1 -1
- package/skills/author-docs/SKILL.md +5 -5
- package/skills/context/SKILL.md +4 -4
- package/skills/log/SKILL.md +6 -6
- package/skills/walkthrough/SKILL.md +1 -1
- package/lib/use_brain.mjs +0 -82
package/lib/uninstall.mjs
CHANGED
|
@@ -3,7 +3,7 @@ import { homedir } from 'os'
|
|
|
3
3
|
import { join } from 'path'
|
|
4
4
|
import { execFileSync } from 'child_process'
|
|
5
5
|
|
|
6
|
-
// Full uninstall — the reverse of setup.mjs. Removes EVERY touch-point
|
|
6
|
+
// Full uninstall — the reverse of setup.mjs. Removes EVERY touch-point Cortex writes onto a machine:
|
|
7
7
|
// 1. ~/.claude.json → mcpServers.cortex
|
|
8
8
|
// 2. ~/.claude/settings.json → Stop/SessionStart/PreCompact cortex hooks
|
|
9
9
|
// 3. ~/.codex/config.toml → [mcp_servers.cortex] + [mcp_servers.cortex.env]
|
|
@@ -34,7 +34,7 @@ export function runUninstall(argv = []) {
|
|
|
34
34
|
const act = (msg) => plan.push(msg)
|
|
35
35
|
const write = (path, data) => { if (!dry) { backup(path); writeFileSync(path, data) } }
|
|
36
36
|
|
|
37
|
-
process.stdout.write(dry ? '\
|
|
37
|
+
process.stdout.write(dry ? '\nCortex uninstall — DRY RUN (nothing will change):\n\n' : '\nCortex uninstall — removing all wiring…\n\n')
|
|
38
38
|
|
|
39
39
|
// 1. MCP server out of ~/.claude.json
|
|
40
40
|
editJson(CLAUDE_JSON, (cfg) => {
|
|
@@ -144,7 +144,7 @@ export function runUninstall(argv = []) {
|
|
|
144
144
|
}
|
|
145
145
|
}
|
|
146
146
|
|
|
147
|
-
if (plan.length === 0) { process.stdout.write(' Nothing to remove — this machine has no
|
|
147
|
+
if (plan.length === 0) { process.stdout.write(' Nothing to remove — this machine has no Cortex wiring.\n\n'); return }
|
|
148
148
|
process.stdout.write(plan.join('\n') + '\n\n')
|
|
149
149
|
if (dry) {
|
|
150
150
|
process.stdout.write('DRY RUN — nothing changed. Re-run without --dry-run to apply.\n')
|
package/package.json
CHANGED
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cortex-author-docs
|
|
3
|
-
description: Push new/changed documentation (specs, plans, design docs) from disk into
|
|
3
|
+
description: Push new/changed documentation (specs, plans, design docs) from disk into Cortex as authored wiki pages. Run after writing a spec/plan/design doc, when the user asks to sync docs to Cortex, or as part of session close-out.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **
|
|
6
|
+
> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
|
|
7
7
|
> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
|
|
8
8
|
|
|
9
9
|
## Why this exists
|
|
10
10
|
|
|
11
11
|
Specs, plans, and design docs get written to disk (a repo's `docs/`, skill-generated design docs)
|
|
12
|
-
and never reach
|
|
12
|
+
and never reach Cortex — so the org brain misses its richest artifacts. A spec IS a page: this
|
|
13
13
|
skill turns pending docs into authored wiki pages. You (the live session) are the pipe — you read
|
|
14
14
|
the doc and author a synthesis. Never dump raw markdown into a page.
|
|
15
15
|
|
|
16
16
|
## When to use
|
|
17
17
|
|
|
18
18
|
- Right after you write or substantially update a spec/plan/design/runbook doc on disk.
|
|
19
|
-
- When the user asks to push/sync docs to
|
|
19
|
+
- When the user asks to push/sync docs to Cortex.
|
|
20
20
|
- During session close-out (`/cortex-log` runs this as a sweep step).
|
|
21
21
|
|
|
22
22
|
## Steps
|
|
@@ -67,7 +67,7 @@ the doc and author a synthesis. Never dump raw markdown into a page.
|
|
|
67
67
|
## Safety rules
|
|
68
68
|
|
|
69
69
|
- Do NOT register or sweep the local brain repo (`~/Documents/brain`) while the Robin parity soak
|
|
70
|
-
is running — the experiment forbids re-syncing Robin into
|
|
70
|
+
is running — the experiment forbids re-syncing Robin into Cortex mid-window.
|
|
71
71
|
- Respect tiers: if a doc is clearly personal/sensitive, author it `confidential` or ask; default
|
|
72
72
|
for work docs is the author path's normal default.
|
|
73
73
|
- This skill writes wiki pages via the `author` tool only. It never sends external messages and
|
package/skills/context/SKILL.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cortex-context
|
|
3
|
-
description: Automatically hydrate
|
|
3
|
+
description: Automatically hydrate Cortex context at the start of a substantive session. Use when Cortex MCP is available and the user has made a real request, so the first answer is grounded in query-centered org context instead of the static baseline alone.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **
|
|
6
|
+
> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
|
|
7
7
|
> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -14,12 +14,12 @@ chit-chat and requests where org context is obviously irrelevant.
|
|
|
14
14
|
## Steps
|
|
15
15
|
|
|
16
16
|
1. Call `session_context` with the user's opening request, preserving the actual topic in their words.
|
|
17
|
-
2. Use that returned block as the primary
|
|
17
|
+
2. Use that returned block as the primary Cortex grounding for the first response.
|
|
18
18
|
3. If `session_context` is unavailable or errors, fall back to `my_context`.
|
|
19
19
|
4. If the conversation materially changes topics later, call `session_context` again for the new topic.
|
|
20
20
|
|
|
21
21
|
## Safety rules
|
|
22
22
|
|
|
23
|
-
- Do not fabricate
|
|
23
|
+
- Do not fabricate Cortex context if the tool fails.
|
|
24
24
|
- Prefer the query-centered `session_context` over static `my_context` whenever the user's topic is clear.
|
|
25
25
|
- Do not call `session_context` for every tiny follow-up; refresh only when the topic meaningfully shifts.
|
package/skills/log/SKILL.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cortex-log
|
|
3
|
-
description: Close out a work session into
|
|
3
|
+
description: Close out a work session into Cortex — summarize what happened, confirm it reached the org, and surface anything teammates should know. Run at or near the end of any working session.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **
|
|
6
|
+
> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
|
|
7
7
|
> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
|
|
8
8
|
|
|
9
9
|
## Model: session-primary, daily-derived
|
|
10
10
|
|
|
11
|
-
The **session is the primary atomic unit** — one session = one durable
|
|
11
|
+
The **session is the primary atomic unit** — one session = one durable Cortex record (via
|
|
12
12
|
`log_session`, keyed by `sessionId`), which is also the per-record privacy unit (`set_record_privacy`
|
|
13
13
|
is per record). Any "what happened today / this week" view is a **derived rollup** over those session
|
|
14
14
|
records, never a separately-authored primary. This mirrors records(atomic) → digests(derived); the
|
|
@@ -16,7 +16,7 @@ personal `/log` skill follows the same shape against the local brain.
|
|
|
16
16
|
|
|
17
17
|
## When to use
|
|
18
18
|
|
|
19
|
-
At the end of a Claude Code session, or after finishing a meaningful phase of work.
|
|
19
|
+
At the end of a Claude Code session, or after finishing a meaningful phase of work. Cortex keeps a
|
|
20
20
|
background auto-capture as a fallback, but this skill is the *authoritative* close-out: it composes a
|
|
21
21
|
clean, structured summary and persists THAT as the session's durable record (superseding the
|
|
22
22
|
auto-capture's raw-transcript re-derivation).
|
|
@@ -33,7 +33,7 @@ No arguments. Read the conversation context.
|
|
|
33
33
|
These are the things a teammate or manager would want to know without reading the whole transcript.
|
|
34
34
|
3. **Persist it as the durable record** — call the `log_session` MCP tool with your curated `summary`
|
|
35
35
|
(plus `project`, and the Claude Code `sessionId` if you know it). This writes YOUR summary as the
|
|
36
|
-
session's authoritative
|
|
36
|
+
session's authoritative Cortex record (`capture_source='skill'`). The background auto-capture is a
|
|
37
37
|
fallback and will not overwrite it; passing the same `sessionId` the auto-capture uses dedupes them
|
|
38
38
|
onto one record. This — not the raw-transcript re-derivation — is the canonical record going forward.
|
|
39
39
|
4. **Confirm + flag privacy** — `log_session` returns a confirmation; if it errors, tell the user to
|
|
@@ -72,7 +72,7 @@ No arguments. Read the conversation context.
|
|
|
72
72
|
> verify a write; the result you already have in hand is the strongest.
|
|
73
73
|
>
|
|
74
74
|
> **What replaces it — at the moment of each write, not at the end:** a rejected `author` comes back
|
|
75
|
-
> as an ORDINARY tool result with **no error flag** — `Could not author "<page>":
|
|
75
|
+
> as an ORDINARY tool result with **no error flag** — `Could not author "<page>": Cortex API 409:
|
|
76
76
|
> <reason>` — and `No change to "<page>"` is a **200 OK that wrote nothing**. Neither is an error at
|
|
77
77
|
> the protocol level, so nothing will interrupt you. **Read the result text of every write; never
|
|
78
78
|
> skim it.** That inline read is where this step's value actually was.
|
|
@@ -3,7 +3,7 @@ name: cortex-walkthrough
|
|
|
3
3
|
description: Run the guided Agnoclast walkthrough for someone new. Use when the person asks for the walkthrough, a tutorial, or getting started — "give me the walkthrough", "walk me through this", "how do I use this", "show me around", "what can this do", "remind me how this works" — or when a brand-new user needs orienting for the first time.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **
|
|
6
|
+
> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
|
|
7
7
|
> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
|
|
8
8
|
|
|
9
9
|
# The Agnoclast walkthrough
|
package/lib/use_brain.mjs
DELETED
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
|
|
2
|
-
import { resolveToken } from './doctor.mjs'
|
|
3
|
-
|
|
4
|
-
// `use-brain` — set (or show) which brain this machine's unattended session captures land in.
|
|
5
|
-
//
|
|
6
|
-
// WHY A SUBCOMMAND EXISTS AT ALL. The server side of this shipped 2026-08-09 with NO client surface:
|
|
7
|
-
// no CLI, no MCP tool, no console setting. The only way to set a capture default was a raw
|
|
8
|
-
// authenticated HTTP call, which meant the only people who could fix a broken capture were the ones
|
|
9
|
-
// who could hand-write a curl with a bearer token. Three real users needed it; one of them is not
|
|
10
|
-
// technical. A fix only its author can operate is not a fix.
|
|
11
|
-
//
|
|
12
|
-
// Pairs with the SessionStart notice: the notice tells you captures are being held and names this
|
|
13
|
-
// command, so the loop from "something is wrong" to "it is fixed" is one paste with no docs.
|
|
14
|
-
|
|
15
|
-
function out(m) { process.stdout.write(m + '\n') }
|
|
16
|
-
|
|
17
|
-
export async function runUseBrain(args) {
|
|
18
|
-
const base = resolveBase(process.env.CORTEX_URL)
|
|
19
|
-
const { token } = resolveToken()
|
|
20
|
-
if (!token) {
|
|
21
|
-
out('Agnoclast: no token found. Run: npx -y @theronap/cortex-mcp setup <token>')
|
|
22
|
-
return 1
|
|
23
|
-
}
|
|
24
|
-
|
|
25
|
-
// Everything after the subcommand is the brain, joined — so an unquoted multi-word name still
|
|
26
|
-
// works. `use-brain Real estate` is what a person actually types; refusing it over a missing pair
|
|
27
|
-
// of quotes would be the same species of unhelpfulness this command exists to remove.
|
|
28
|
-
const wanted = (args ?? []).filter((a) => !a.startsWith('--')).join(' ').trim()
|
|
29
|
-
const url = `${base}/api/brain/capture-default`
|
|
30
|
-
|
|
31
|
-
if (!wanted) {
|
|
32
|
-
// No argument: report the current state rather than erroring. "What is it set to?" is a fair
|
|
33
|
-
// question and the answer is one GET away.
|
|
34
|
-
try {
|
|
35
|
-
const res = await fetchCortex(url, { headers: { Authorization: `Bearer ${token}` } })
|
|
36
|
-
if (!res.ok) {
|
|
37
|
-
const body = await res.text()
|
|
38
|
-
out(`Agnoclast: could not read your capture settings — ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}`)
|
|
39
|
-
return 1
|
|
40
|
-
}
|
|
41
|
-
const { defaults } = await res.json()
|
|
42
|
-
if (!defaults?.length) {
|
|
43
|
-
out('Agnoclast: no capture brain set. Your unattended session captures land in a brain only if')
|
|
44
|
-
out(' you belong to exactly one; otherwise they are HELD outside every brain until you set this.')
|
|
45
|
-
out(' Set one: npx -y @theronap/cortex-mcp use-brain "<brain name or org id>"')
|
|
46
|
-
return 0
|
|
47
|
-
}
|
|
48
|
-
for (const d of defaults) out(`Agnoclast: ${d.sourceType} captures land in "${d.orgName}" (${d.orgId})`)
|
|
49
|
-
return 0
|
|
50
|
-
} catch (e) {
|
|
51
|
-
out(`Agnoclast: could not reach the server (${e?.message ?? String(e)})`)
|
|
52
|
-
return 1
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
try {
|
|
57
|
-
const res = await fetchCortex(url, {
|
|
58
|
-
method: 'POST',
|
|
59
|
-
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
|
|
60
|
-
body: JSON.stringify({ sourceType: 'claude-code', brain: wanted }),
|
|
61
|
-
})
|
|
62
|
-
const body = await res.text()
|
|
63
|
-
if (!res.ok) {
|
|
64
|
-
let msg = classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message
|
|
65
|
-
// The server's own error text is better than a generic one here: a 404 names the brain that was
|
|
66
|
-
// not found, and a 409 lists the org ids of an ambiguous name — which is the whole remedy.
|
|
67
|
-
try { const j = JSON.parse(body); if (j.error) msg = j.error } catch { /* keep the classified message */ }
|
|
68
|
-
out(`Agnoclast: ${msg}`)
|
|
69
|
-
return 1
|
|
70
|
-
}
|
|
71
|
-
const j = JSON.parse(body)
|
|
72
|
-
out(`Agnoclast: ✓ your Claude Code sessions now land in "${j.brain}".`)
|
|
73
|
-
// Say plainly what this does NOT do. The setter's own server-side note makes the same point,
|
|
74
|
-
// because "I fixed it" reading as "and the backlog is handled" is how held records stay held.
|
|
75
|
-
out(' Sessions captured BEFORE now are still held — they keep their original dates until sorted.')
|
|
76
|
-
out(' Ask your assistant to file them (they may not all belong in the same brain).')
|
|
77
|
-
return 0
|
|
78
|
-
} catch (e) {
|
|
79
|
-
out(`Agnoclast: could not reach the server (${e?.message ?? String(e)})`)
|
|
80
|
-
return 1
|
|
81
|
-
}
|
|
82
|
-
}
|