@danielblomma/cortex-mcp 0.4.5 → 0.6.4

package/README.md

@@ -1,5 +1,12 @@
+<p align="center">
+  <img src="docs/logo.png" alt="Cortex" width="600" />
+</p>
+
 # Cortex MCP
 
+[![npm version](https://img.shields.io/npm/v/%40danielblomma%2Fcortex-mcp)](https://www.npmjs.com/package/@danielblomma/cortex-mcp)
+[![npm downloads](https://img.shields.io/npm/dw/%40danielblomma%2Fcortex-mcp)](https://www.npmjs.com/package/@danielblomma/cortex-mcp)
+
 `@danielblomma/cortex-mcp` is a local, repo-scoped context platform for coding assistants.
 It indexes your codebase into structured entities (files, rules, ADRs) and exposes that context over MCP (JSON-RPC over stdio).
 
@@ -15,43 +22,10 @@ It indexes your codebase into structured entities (files, rules, ADRs) and expos
 
 ## Core Features
 
-- Semantic search (files, rules, ADRs).
-- Graph relationships between entities and constraints.
+- Semantic search across files, rules, and ADRs.
+- Graph relationships between entities and architectural constraints.
 - Architectural rules and ADR context for implementation decisions.
-
-## Advanced Features (Experimental)
-
-Cortex can extract function-level chunks and build call graphs in experimental builds:
-
-- `context.find_callers` - what calls this function?
-- `context.trace_calls` - what does this function call?
-- `context.impact_analysis` - what is impacted if this function changes?
-- Requires JavaScript/TypeScript codebase and semantic chunking/call graph indexing enabled.
-
-These APIs are experimental and may not be exposed in every installation.
-
-## Chunking Strategy (Code)
-
-When semantic chunking is enabled, large function/method chunks are split into overlap windows during ingest.
-
-Defaults:
-
-- `CORTEX_CHUNK_WINDOW_LINES=80`
-- `CORTEX_CHUNK_OVERLAP_LINES=16`
-- `CORTEX_CHUNK_SPLIT_MIN_LINES=120`
-- `CORTEX_CHUNK_MAX_WINDOWS=8`
-
-Behavior:
-
-- Chunks are split only when the chunk body exceeds the split threshold.
-- Windows slide forward using configured overlap (`next_start = previous_end - overlap`).
-- The last allowed window always stretches to the end of the chunk body.
-- Window chunks inherit metadata (`status`, `source_of_truth`) from their parent chunk.
-- Window chunks inherit parent graph edges for `CALLS` and `IMPORTS` to keep traversal/ranking consistent.
-
-Verification:
-
-- Overlap and windowing regressions are covered in `tests/context-regressions.test.mjs`.
+- Live TUI dashboard showing what Cortex adds to your repo.
 
 ## Requirements
 
@@ -76,6 +50,7 @@ cortex init --bootstrap
 This will:
 
 - scaffold `.context/`, `scripts/`, `mcp/`, `.githooks/`, and docs files
+- activate git hooks for checkout, pull/merge, commit, and rewrite events
 - build and prepare the local MCP server
 - try to auto-register MCP connections for Claude/Codex (if installed)
 - start background sync unless disabled
@@ -86,14 +61,12 @@ Disable watcher setup:
 cortex init --bootstrap --no-watch
 ```
 
-Check semantic search readiness:
+Check context status:
 
 ```bash
 cortex status
 ```
 
-Look for `semantic_search=embedding+lexical (ready)` to confirm full semantic mode.
-
 ## Verify MCP Connection
 
 Claude:
@@ -204,6 +177,31 @@ Input:
 - "Show related files for this ADR."
 - "What active architectural rules apply to this API?"
 
+## Dashboard
+
+A live TUI that shows what Cortex adds to your repository at a glance.
+
+```bash
+cortex dashboard
+```
+
+![Cortex dashboard](https://raw.githubusercontent.com/DanielBlomma/cortex/main/docs/dashboard-screenshot.png)
+
+The dashboard displays:
+
+- **WITHOUT vs WITH CORTEX** — side-by-side comparison of raw files versus indexed entities (files, chunks, relations, rules, embeddings, trust signals).
+- **TOKENS** — per-task token estimate comparing typical LLM file reads without Cortex (~12 files) versus Cortex searches (~3 queries). Shows the reduction ratio and percentage.
+- **CORTEX ADDS** — summary of what Cortex layers on top: chunks, relations, rules, embeddings, and which capabilities are unlocked (semantic search, graph traversal, impact analysis).
+- **RELATIONS** — bar chart of relation types in the graph (CALLS, DEFINES, CONSTRAINS, IMPLEMENTS, IMPORTS, SUPERSEDES) and their counts.
+- **HEALTH** — freshness percentage (how up-to-date the index is relative to uncommitted changes), last sync timestamp, and embedding status with model name.
+- **TOP CONNECTED** — the five most connected entities in the graph by edge count, showing which files or rules are central to the codebase.
+
+Options:
+
+- `--interval <sec>` — auto-refresh interval (default: 2 seconds).
+- Press `r` to force refresh, `q` to quit.
+- Non-TTY output (piped) produces a single snapshot with ANSI stripped.
+
 ## Common Commands
 
 ```text
@@ -213,10 +211,8 @@ cortex mcp
 cortex bootstrap
 cortex update
 cortex status
+cortex dashboard [--interval <sec>]
 cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
-cortex note <title> [text]
-cortex plan
-cortex todo [text|list|done <id>|reopen <id>|remove <id>]
 cortex help
 ```
 

package/bin/cortex.mjs

@@ -16,7 +16,6 @@ const GITIGNORE_LINES = [
   ".context/db/",
   ".context/embeddings/",
   ".context/cache/",
-  ".context/plan/",
   ".context/hooks/",
   ".npm-cache/",
   "mcp/.npm-cache/",
@@ -56,9 +55,8 @@ function printHelp() {
   console.log("  cortex ingest [--changed] [--verbose]");
   console.log("  cortex embed [--changed]");
   console.log("  cortex graph-load [--no-reset]");
-  console.log("  cortex note <title> [text]");
-  console.log("  cortex plan");
-  console.log("  cortex todo [text|list|done <id>|reopen <id>|remove <id>]");
+  console.log("  cortex memory-compile [--dry-run] [--verbose]");
+  console.log("  cortex memory-lint [--verbose] [--json]");
   console.log("  cortex help");
 }
 
@@ -257,32 +255,6 @@ function upsertSectionByMarkers(targetPath, startMarker, endMarker, sectionConte
 
 function installClaudeCommands(targetDir) {
   const commandSpecs = [
-    {
-      file: "note.md",
-      content: `---
-description: "Save important project context into Cortex notes"
-argument-hint: "<title> [details]"
----
-Execute: cortex note "$ARGUMENTS"
-`
-    },
-    {
-      file: "todo.md",
-      content: `---
-description: "Add or list Cortex TODOs"
-argument-hint: "<text|list|done <id>|reopen <id>|remove <id>>"
----
-Execute: cortex todo "$ARGUMENTS"
-`
-    },
-    {
-      file: "plan.md",
-      content: `---
-description: "Show Cortex auto-plan progress"
----
-Execute: cortex plan
-`
-    },
     {
       file: "context-update.md",
       content: `---
@@ -309,10 +281,7 @@ function installCodexAgentsSection(targetDir) {
   const startMarker = "<!-- cortex:auto:start -->";
   const endMarker = "<!-- cortex:auto:end -->";
   const section = `## Cortex Auto Workflow
-- Use \`cortex todo "<task>"\` for every new implementation task.
-- Use \`cortex note "<title>" "<details>"\` when an important decision is made.
 - Run \`cortex update\` before completing substantial code changes.
-- Use \`cortex plan\` to inspect current progress and next command.
 - If background sync is enabled, check with \`cortex watch status\`.`;
   const changed = upsertSectionByMarkers(agentsPath, startMarker, endMarker, section);
   return { path: agentsPath, changed };
@@ -461,6 +430,27 @@ async function connectMcpClients(targetDir, options = {}) {
   return connected;
 }
 
+async function maybeInstallGitHooks(targetDir) {
+  const installScript = path.join(targetDir, "scripts", "install-git-hooks.sh");
+  if (!fs.existsSync(installScript)) {
+    return false;
+  }
+
+  const gitRepo = await runCommandResult("git", ["rev-parse", "--show-toplevel"], targetDir, "ignore");
+  if (!gitRepo.ok) {
+    console.log("[cortex] git hooks skipped (not a Git repository)");
+    return false;
+  }
+
+  try {
+    await runCommand("bash", [installScript], targetDir);
+    return true;
+  } catch (error) {
+    console.log(`[cortex] failed to install git hooks: ${toErrorMessage(error)}`);
+    return false;
+  }
+}
+
 function ensureProjectInitialized(targetDir) {
   const mcpPackageJson = path.join(targetDir, "mcp", "package.json");
   if (!fs.existsSync(mcpPackageJson)) {
@@ -504,7 +494,7 @@ async function ensureProjectInitializedForMcp(targetDir) {
     fs.mkdirSync(targetDir, { recursive: true });
     installScaffold(targetDir, false);
     installAssistantHelpers(targetDir);
-    await markPlanEvent(targetDir, "init");
+    await maybeInstallGitHooks(targetDir);
     console.log(`[cortex] auto-init completed in ${targetDir}`);
   }
 
@@ -522,18 +512,6 @@ async function runContextCommand(cwd, contextArgs) {
   await runCommand("bash", [contextScript, ...contextArgs], cwd);
 }
 
-async function markPlanEvent(targetDir, eventName) {
-  const planScript = path.join(targetDir, "scripts", "plan-state.sh");
-  if (!fs.existsSync(planScript)) {
-    return;
-  }
-
-  const result = await runCommandResult("bash", [planScript, "event", eventName], targetDir, "ignore");
-  if (!result.ok) {
-    console.log(`[cortex] warning: failed to update automatic plan state for event '${eventName}'`);
-  }
-}
-
 async function run() {
   const cliVersion = readCliVersion();
   process.env.CORTEX_CLI_VERSION = cliVersion;
@@ -558,11 +536,11 @@ async function run() {
     fs.mkdirSync(target, { recursive: true });
     installScaffold(target, force);
     const helpers = installAssistantHelpers(target);
-    await markPlanEvent(target, "init");
+    await maybeInstallGitHooks(target);
 
     console.log(`[cortex] initialized in ${target}`);
     console.log("[cortex] scaffold copied: .context/, scripts/, mcp/, .githooks/, docs/");
-    console.log(`[cortex] Claude commands ready: /note /todo /plan /context-update (${helpers.claude.total} files)`);
+    console.log(`[cortex] Claude commands ready: /context-update (${helpers.claude.total} files)`);
     if (helpers.codex.changed) {
       console.log("[cortex] Codex workflow instructions added to AGENTS.md");
     } else {
@@ -600,10 +578,7 @@ async function run() {
     }
 
     if (connect) {
-      const connected = await connectMcpClients(target);
-      if (connected > 0) {
-        await markPlanEvent(target, "connect");
-      }
+      await connectMcpClients(target);
     }
 
     if (watch && bootstrap) {
@@ -619,10 +594,7 @@ async function run() {
     if (helpers.claude.changed > 0 || helpers.codex.changed) {
       console.log("[cortex] assistant helpers updated (.claude/commands + AGENTS.md)");
     }
-    const connected = await connectMcpClients(target, { skipBuild });
-    if (connected > 0) {
-      await markPlanEvent(target, "connect");
-    }
+    await connectMcpClients(target, { skipBuild });
     return;
   }
 
@@ -648,11 +620,11 @@ async function run() {
     "ingest",
     "embed",
     "graph-load",
+    "dashboard",
     "watch",
-    "note",
-    "plan",
-    "todo",
-    "refresh"
+    "refresh",
+    "memory-compile",
+    "memory-lint"
   ]);
 
   if (!passthrough.has(command)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "0.4.5",
+  "version": "0.6.4",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -24,17 +24,29 @@
     "claude",
     "codex"
   ],
+  "exports": {
+    ".": "./bin/cortex.mjs",
+    "./types": "./mcp/dist/types.js"
+  },
   "bin": {
     "cortex": "bin/cortex.mjs"
   },
   "files": [
     "bin",
-    "scaffold",
+    "scaffold/.context",
+    "scaffold/.githooks",
+    "scaffold/docs",
+    "scaffold/scripts",
+    "scaffold/mcp/src",
+    "scaffold/mcp/tests",
+    "scaffold/mcp/package.json",
+    "scaffold/mcp/package-lock.json",
+    "scaffold/mcp/tsconfig.json",
     "README.md",
     "docs/MCP_MARKETPLACE.md"
   ],
   "scripts": {
-    "test": "node tests/plan-state.test.mjs",
+    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/javascript-parser.test.mjs tests/sql-parser.test.mjs tests/config-parser.test.mjs tests/resources-parser.test.mjs tests/vbnet-parser.test.mjs tests/cpp-parser.test.mjs tests/multi-level.test.mjs",
     "release:sync-version": "node scripts/sync-release-version.mjs",
     "release:check-version-sync": "node scripts/sync-release-version.mjs --check",
     "prepublishOnly": "echo 'Ready to publish to npm'"

package/scaffold/.context/ontology.cypher

@@ -45,12 +45,46 @@ CREATE NODE TABLE IF NOT EXISTS Chunk(
   kind STRING,
   signature STRING,
   body STRING,
+  description STRING,
   start_line INT64,
   end_line INT64,
   language STRING,
+  exported BOOL,
   checksum STRING,
   updated_at STRING,
+  source_of_truth BOOL,
+  trust_level INT64,
+  status STRING,
+  PRIMARY KEY(id)
+);
+
+CREATE NODE TABLE IF NOT EXISTS Module(
+  id STRING,
+  path STRING,
+  name STRING,
+  summary STRING,
+  file_count INT64,
+  exported_symbols STRING,
+  updated_at STRING,
+  source_of_truth BOOL,
+  trust_level INT64,
+  status STRING,
+  PRIMARY KEY(id)
+);
+
+CREATE NODE TABLE IF NOT EXISTS Project(
+  id STRING,
+  path STRING,
+  name STRING,
+  kind STRING,
+  language STRING,
+  target_framework STRING,
+  summary STRING,
+  file_count INT64,
+  updated_at STRING,
+  source_of_truth BOOL,
   trust_level INT64,
+  status STRING,
   PRIMARY KEY(id)
 );
 
@@ -61,3 +95,16 @@ CREATE REL TABLE IF NOT EXISTS SUPERSEDES(FROM ADR TO ADR, reason STRING);
 CREATE REL TABLE IF NOT EXISTS DEFINES(FROM File TO Chunk);
 CREATE REL TABLE IF NOT EXISTS CALLS(FROM Chunk TO Chunk, call_type STRING);
 CREATE REL TABLE IF NOT EXISTS IMPORTS(FROM Chunk TO File, import_name STRING);
+CREATE REL TABLE IF NOT EXISTS CALLS_SQL(FROM File TO Chunk, note STRING);
+CREATE REL TABLE IF NOT EXISTS USES_CONFIG_KEY(FROM File TO Chunk, note STRING);
+CREATE REL TABLE IF NOT EXISTS USES_RESOURCE_KEY(FROM File TO Chunk, note STRING);
+CREATE REL TABLE IF NOT EXISTS USES_SETTING_KEY(FROM File TO Chunk, note STRING);
+CREATE REL TABLE IF NOT EXISTS CONTAINS(FROM Module TO File);
+CREATE REL TABLE IF NOT EXISTS CONTAINS_MODULE(FROM Module TO Module);
+CREATE REL TABLE IF NOT EXISTS EXPORTS(FROM Module TO Chunk);
+CREATE REL TABLE IF NOT EXISTS INCLUDES_FILE(FROM Project TO File);
+CREATE REL TABLE IF NOT EXISTS REFERENCES_PROJECT(FROM Project TO Project, note STRING);
+CREATE REL TABLE IF NOT EXISTS USES_RESOURCE(FROM File TO File, note STRING);
+CREATE REL TABLE IF NOT EXISTS USES_SETTING(FROM File TO File, note STRING);
+CREATE REL TABLE IF NOT EXISTS USES_CONFIG(FROM File TO File, note STRING);
+CREATE REL TABLE IF NOT EXISTS TRANSFORMS_CONFIG(FROM File TO File, note STRING);

package/scaffold/.githooks/post-commit

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$REPO_ROOT" ]]; then
+  exit 0
+fi
+
+RUNNER="$REPO_ROOT/.githooks/_cortex-update-runner.sh"
+if [[ ! -x "$RUNNER" ]]; then
+  exit 0
+fi
+
+nohup bash "$RUNNER" >/dev/null 2>&1 &

package/scaffold/.githooks/post-rewrite

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+command_name="${1:-}"
+case "$command_name" in
+  amend|rebase)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$REPO_ROOT" ]]; then
+  exit 0
+fi
+
+RUNNER="$REPO_ROOT/.githooks/_cortex-update-runner.sh"
+if [[ ! -x "$RUNNER" ]]; then
+  exit 0
+fi
+
+nohup bash "$RUNNER" >/dev/null 2>&1 &

package/scaffold/mcp/package-lock.json

@@ -1039,12 +1039,12 @@
       }
     },
     "node_modules/express-rate-limit": {
-      "version": "8.2.1",
-      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.2.1.tgz",
-      "integrity": "sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==",
+      "version": "8.3.1",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.1.tgz",
+      "integrity": "sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw==",
       "license": "MIT",
       "dependencies": {
-        "ip-address": "10.0.1"
+        "ip-address": "10.1.0"
       },
       "engines": {
         "node": ">= 16"
@@ -1284,9 +1284,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.5",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.5.tgz",
-      "integrity": "sha512-3qq+FUBtlTHhtYxbxheZgY8NIFnkkC/MR8u5TTsr7YZ3wixryQ3cCwn3iZbg8p8B88iDBBAYSfZDS75t8MN7Vg==",
+      "version": "4.12.7",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.7.tgz",
+      "integrity": "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -1361,9 +1361,9 @@
       "license": "ISC"
     },
     "node_modules/ip-address": {
-      "version": "10.0.1",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.0.1.tgz",
-      "integrity": "sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==",
+      "version": "10.1.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
+      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -1679,9 +1679,9 @@
       }
     },
     "node_modules/path-to-regexp": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz",
-      "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==",
+      "version": "8.4.0",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.0.tgz",
+      "integrity": "sha512-PuseHIvAnz3bjrM2rGJtSgo1zjgxapTLZ7x2pjhzWwlp4SJQgK3f3iZIQwkpEnBaKz6seKBADpM4B4ySkuYypg==",
       "license": "MIT",
       "funding": {
         "type": "opencollective",
@@ -2275,9 +2275,9 @@
       }
     },
     "node_modules/tar": {
-      "version": "7.5.10",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.10.tgz",
-      "integrity": "sha512-8mOPs1//5q/rlkNSPcCegA6hiHJYDmSLEI8aMH/CdSQJNWztHC9WHNam5zdQlfpTwB9Xp7IBEsHfV5LKMJGVAw==",
+      "version": "7.5.11",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.11.tgz",
+      "integrity": "sha512-ChjMH33/KetonMTAtpYdgUFr0tbz69Fp2v7zWxQfYZX4g5ZN2nOBXm1R2xyA+lMIKrLKIoKAwFj93jE/avX9cQ==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/fs-minipass": "^4.0.0",

package/scaffold/mcp/package.json

@@ -19,7 +19,9 @@
   },
   "overrides": {
     "cmake-js": "^8.0.0",
-    "tar": "^7.5.9"
+    "express-rate-limit": "^8.3.1",
+    "hono": "^4.12.7",
+    "tar": "^7.5.11"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",